Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docusaurus v3 upgrade #503

Merged
merged 20 commits into from
Sep 18, 2024
Merged

Docusaurus v3 upgrade #503

merged 20 commits into from
Sep 18, 2024

Conversation

kcpevey
Copy link
Contributor

@kcpevey kcpevey commented Aug 9, 2024

This PR upgrades the docs to Docusaurus V3. There are some breaking changes and this PR includes all the required changes to make the docs build again after the upgrade.

Some things to note:

  • the icon admonition we had in the docusaurus config is no longer allowed. I had a hard time understanding the admonitions, but it seems like the icon admonition was being customized in /src/theme/components/admonitions.scss and the examples for V3 are all using js. Those are outside of my skillset so if we want to keep that, I'll need some help with that bit.
  • I'm not very familiar with yarn, but I followed the directions to upgrade all the packages and update the package.json and yarn.lock. I think I did that right?
  • A lot of the required updates were around links. While I was fixing the link syntax, if the link was not accessible (i.e. was just underneath the word "here"), I reworded the text so the link text would be more descriptive. That is only reason for the wording changes in this PR.

Reference Issues or PRs

Resolves #395

What does this implement/fix?

Put a x in the boxes that apply

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds a feature)
  • Breaking change (fix or feature that would cause existing features not to work as expected)
  • Documentation Update
  • Code style update (formatting, renaming)
  • Refactoring (no functional changes, no API changes)
  • Build related changes
  • Other (please describe):

Testing

  • Did you test the pull request locally?
  • Did you add new tests?

Documentation

Access-centered content checklist

Text styling

  • The content is written with plain language (where relevant).
  • If there are headers, they use the proper header tags (with only one level-one header: H1 or # in markdown).
  • All links describe where they link to (for example, check the Nebari website).
  • This content adheres to the Nebari style guides.

Non-text content

  • All content is represented as text (for example, images need alt text, and videos need captions or descriptive transcripts).
  • If there are emojis, there are not more than three in a row.
  • Don't use flashing GIFs or videos.
  • If the content were to be read as plain text, it still makes sense, and no information is missing.

Any other comments?

Copy link

netlify bot commented Aug 9, 2024

Deploy Preview for nebari-docs ready!

Name Link
🔨 Latest commit d1e9cd6
🔍 Latest deploy log https://app.netlify.com/sites/nebari-docs/deploys/66eb194f35e7a90008e11b71
😎 Deploy Preview https://deploy-preview-503--nebari-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@kcpevey
Copy link
Contributor Author

kcpevey commented Aug 13, 2024

Can I get some help debugging the failure in the CI build?

The error is The engine "node" is incompatible with this module. Expected version ">=18.0". Got "16.20.2" but I've specified node>18 here. It builds fine on my machine so I think it must be something to do with the CI runner but I dont know enough about npm/yarn to sort it out.

@pavithraes
Copy link
Member

pavithraes commented Aug 16, 2024

Checked Netlify per @krassowski suggestions, and we do configure the Node version there. Updated to use 18.x now:

Screenshot 2024-08-16 at 2 42 42 PM

Re-built the site, and seems to be working on Netlify now. The preview above also works.

I am not sure why the GitHub CI is still red and not updating. @kcpevey I'll push an empty commit to this PR to re-trigger CI. Please let me know if you'd like me to refrain from pushing up to your branch in the future. :)

Signed-off-by: Pavithra Eswaramoorthy <pavithraes@outlook.com>
@kcpevey
Copy link
Contributor Author

kcpevey commented Aug 16, 2024

Please let me know if you'd like me to refrain from pushing up to your branch in the future.

I'll take all the help I can get - I always welcome collaboration :)

Thank you so much for looking into this @pavithraes ! And thanks for the assistance on finding the solution @krassowski !

@kcpevey kcpevey marked this pull request as ready for review August 16, 2024 17:29
@kcpevey
Copy link
Contributor Author

kcpevey commented Aug 16, 2024

This is now ready for review.

One thing that I do need resolved is the icon admonition (discussed in the description). If we're fine to remove, then its done. If it needs to stay, then I'll need help re-implementing it in a way that docusaurus v3 likes.

@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 2, 2024

I removed the icon admonition as I think its no longer necessary. This is ready for review.

@viniciusdc
Copy link
Contributor

nice! Thanks @kcpevey this will likely be the last in the order of merges after your #502 and #476

@kcpevey kcpevey removed the needs: review 👀 This PR is complete and ready for reviewing label Sep 10, 2024
@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 10, 2024

I'll have to do conflict resolution again whenever we are close to merging.

@viniciusdc
Copy link
Contributor

Hi @kcpevey as #502 what's the status on this PR, is it ready for review?

@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 11, 2024

@viniciusdc Now that blocking PR has been merged, I'll resolve conflicts and get things working again. I'll ping you when its ready for final review.

@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 11, 2024

@viniciusdc this is ready for a final look!

@viniciusdc
Copy link
Contributor

viniciusdc commented Sep 11, 2024

@kcpevey I've noticed from the current built version of this PR, that some of the admonition colors and codeblocks styles are not showing up correctly, is this intended?

before:

image

current PR build:

image

@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 11, 2024

I've noticed from the current built version of this PR, that some of the admonition colors and codeblocks styles are not showing up correctly, is this intended?

Hmmm. I'll have to look more closely. I did make a change to admonitions that may be having an effect here.

@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 12, 2024

@viniciusdc The styling that was previously working for the admonitions is no longer being used. All of the admonitions now are using the css rules that start with alert (e.g. even for note). So the current rules are not applied.

There is also a comment in admonitions.scss about alerts. I played with this a bit, but the behavior seems to have changed and/or I dont have the skillz needed to sort it out.

So at this point, everything in admonitions.scss is being ignored and we are just getting the default admonition styling. I'm not sure if there is anyone available to spend the time to sort this out right now.

@viniciusdc
Copy link
Contributor

viniciusdc commented Sep 13, 2024

Thats okay thank you for having a look into it @kcpevey -- wonder if this might be due to docssaurus-sass plug-in

@kcpevey
Copy link
Contributor Author

kcpevey commented Sep 18, 2024

wonder if this might be due to docssaurus-sass plug-in

Its possible?

We brought up the plan to open an issue to resolve the admonition styling in a separate issue/PR and go ahead and merge this one since its so big. No one disagreed, so @viniciusdc I think we're good to go ahead and merge?

@viniciusdc viniciusdc merged commit 467942a into main Sep 18, 2024
6 checks passed
@viniciusdc viniciusdc deleted the docusaurus_v3 branch September 18, 2024 18:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Done 💪🏾
Development

Successfully merging this pull request may close these issues.

Upgrade to Docusaurus 3.0
3 participants